2018-05-28

Hyperledger Composer教程-创建、开发、发布智能合约

前提条件

本文的Hyperledger Fabric版本为v1.1， Hyperledger Composer的版本为v0.19.5，而且必须已经完成『Hyperledger Fabric教程3-安装开发环境』的安装。

综述

本教程基于Hyperledger Fabric + Composer开发『智能合约』程序并发布到链上，为了快速应用，本机运行于默认的例子，即单个peer、单个orderer的机制，以下是进程：

CONTAINER ID        NAME                     CPU %               MEM USAGE / LIMIT     MEM %               NET
1ed7283b08fa        peer0.org1.example.com   1.59%               28.93MiB / 1.925GiB   1.47%               40.1kB /
f6d811ad71f0        ca.org1.example.com      0.00%               5.746MiB / 1.925GiB   0.29%               7.62kB /
073d0d94c129        couchdb                  0.29%               92.36MiB / 1.925GiB   4.69%               24.5kB /
269b305cf916        orderer.example.com      0.01%               4.848MiB / 1.925GiB   0.25%               20.8kB /

为了方便理解，本教程分为6个步骤完成整个智能合约的开发，分别如下：

Step 1-创建智能合约框架
Step 2-编写智能合约代码
Step 3-生成智能合约归档
Step 4-发布智能合约程序
Step 5-生成REST服务端
Step 6-生成Angular客户端

Step 1-创建智能合约框架

该业务网络关键概念为BND，它为区块链解决方案定义数据模型、事务逻辑和访问控制规则等，本文利用利用composer创建的智能合约，因此智能合约的框架采用『Yeoman』生成器生成，该命令行工具再前提条件里已经默认安装了，如果你电脑没有，请自行安装即可，以下是执行步骤：

使用『Yeoman』创建一个骨架业务网络。此命令将需要业务网络名称，说明，作者姓名，作者电子邮件地址，许可证选择和命名空间。
```
yo hyperledger-composer:businessnetwork
```
输入tutorial-network 网络名称以及所需的描述信息，作者姓名和作者电子邮件。
选择Apache-2.0 作为许可证。
选择org.example.mynetwork 作为命名空间。
选择No 当被问及是否生成一个空网络时。

最终会在该命令下创建文件夹tutorial-network，文件的结构如下：

.
|-- README.md
|-- features
|   |-- sample.feature
|   `-- support
|       `-- index.js
|-- lib
|   `-- logic.js
|-- models
|   `-- org.example.mynetwork.cto
|-- package.json
|-- permissions.acl
`-- test
    `-- logic.js

5 directories, 8 files

智能合约的框架已经建立，接下来就要针对具体的业务，定义具体的事务处理逻辑、数据模型、访问控制规则等。

Step 2-编写智能合约代码

智能合约由资产、参与者、交易、访问控制规则以及可选的事件、查询组成。前面通过命令行『Yeoman』生成的有以下文件：

model(.cto)文件，包含了业务网络中所有资产、参加者和事务类定义
permissions(.acl)文件，基本访问控制规则的访问控制
logic(.js)文件，包含事务处理器功能的脚本，为智能合约的逻辑处理
package配置文件，包含该智能合约的版本号等定义，后续更新业务网络需要修改本文件的版本号

因此主要从添加模型文件、业务逻辑、访问控制三个方面编写智能合约代码，实现业务逻辑。

在编写智能合约时，本人采用的是Atom文本编辑器，配合安装atom的hyperledger的插件，实现智能合约代码高亮、代码提示等功能，建议读者在本地编写完毕，再上传到服务端，或者通过vim在服务端直接编辑。同时，添加的模型文件、业务逻辑处理、访问控制均采用hyperledger composer的建模语言编写，具体建模语言的语法风格，后续会单独有博文介绍。

添加模型文件

模型文件包含每类资产，交易，参与者和事件的定义。它隐含地扩展了建模语言文档中描述的Hyperledger Composer系统模型。打开org.example.mynetwork.cto文件，替换为以下内容：

/**
 * My commodity trading network
 */
namespace org.example.mynetwork
asset Commodity identified by tradingSymbol {
    o String tradingSymbol
    o String description
    o String mainExchange
    o Double quantity
    --> Trader owner
}
participant Trader identified by tradeId {
    o String tradeId
    o String firstName
    o String lastName
}
transaction Trade {
    --> Commodity commodity
    --> Trader newOwner
}

添加业务逻辑

在模型文件中，Trade定义了事务，指定与资产和参与者的关系。事务处理函数文件包含执行模型文件中定义的事务的JavaScript逻辑。打开login.js脚本文件，替换以下内容：

/**
 * Track the trade of a commodity from one trader to another
 * @param {org.example.mynetwork.Trade} trade - the trade to be processed
 * @transaction
 */
async function tradeCommodity(trade) {
    trade.commodity.owner = trade.newOwner;
    let assetRegistry = await getAssetRegistry('org.example.mynetwork.Commodity');
    await assetRegistry.update(trade.commodity);
}

添加访问控制

访问控制规则控制业务模型的访问规则，通过此规则可以控制通道访问资源的策略，打开permissions.acl文件，替换以下内容：

/**
 * Access control rules for tutorial-network
 */
rule Default {
    description: "Allow all participants access to all resources"
    participant: "ANY"
    operation: ALL
    resource: "org.example.mynetwork.*"
    action: ALLOW
}

rule SystemACL {
  description:  "System ACL to permit all access"
  participant: "ANY"
  operation: ALL
  resource: "org.hyperledger.composer.system.**"
  action: ALLOW
}

Step 3-生成智能合约归档

通过『Yeoman』生成智能合约的框架，并编写了具体的数据模型、逻辑事务处理，现在需要将已经完成的智能合约进行打包操作，以便在下一步进行发布到区块链网络节点中。

使用命令行，导航到tutorial-network根目录
从tutorial-network目录中运行以下命令：
```
composer archive create -t dir -n .
```
该命令会取文件下的package.json的的版本号"version": "0.0.1",因此，该命令运行后，在该tutorial-network目录中创建了一个调用的智能合约存档文件,文件以智能合约名+@+版本号+bnd组合，如**tutorial-network@0.0.1.bna**

有了该bna的归档文件，就可以发布到区块链的节点中了，很快就可以实现给力的区块链应用了。

Step 4-发布智能合约程序

本机已经部署启动了hyperledger的基础区块链网络，Orderer+Peer+Couchdb+Ca,通过命令docker stats显示如下：

CONTAINER ID        NAME                     CPU %               MEM USAGE / LIMIT     MEM %               NET
1ed7283b08fa        peer0.org1.example.com   1.59%               28.93MiB / 1.925GiB   1.47%               40.1kB /
f6d811ad71f0        ca.org1.example.com      0.00%               5.746MiB / 1.925GiB   0.29%               7.62kB /
073d0d94c129        couchdb                  0.29%               92.36MiB / 1.925GiB   4.69%               24.5kB /
269b305cf916        orderer.example.com      0.01%               4.848MiB / 1.925GiB   0.25%               20.8kB /

初始容器为4个，若智能合约发布成功，会有新的容器出现，本发布在基于你区块链网络能正常运行，并已经创建PeerAdmin管理员，并且必须创建新参与者，身份和关联卡才能成为『网络管理员』。最后，通过命令导入『网络管理员』业务网卡才能使用。导入成功与否，可以通过ping命令检查它是否正在响应，具体步骤如下：

安装智能合约

导航切换目录到『tutorial-network』，运行一下命令：

composer network install --card PeerAdmin@hlfv1 --archiveFile tutorial-network@0.0.1.bna

输出结果如下：

✔ Installing business network. This may take a minute...
Successfully installed business network tutorial-network, version 0.0.1

Command succeeded

该composer network install命令需要一个PeerAdmin业务网卡（在这种情况下，预先创建并导入一个网卡）以及.bna定义业务网络的文件路径。本文的PeerAdmin业务网卡通过composer工程提供的createPeerAdminCard.sh脚本执行生产并导入，读者也可以自行通过composer card create命令创建具体的连接的管理员业务网卡，创建命令如下：

card create -p DevServer_connection.json -u PeerAdmin -c "${CERT}" -k "${PRIVATE_KEY}" -r PeerAdmin -r ChannelAdmin --file $CARDOUTPUT

导入命令如下：

card import --file /tmp/PeerAdmin@hlfv1.card

最后通过，card list查看是否已经导入成功。

该『PeerAdmin@hlfv1.card』包含了接入节点所需要的私钥和公钥证书、登录用户名密码、连接peer节点的网络地址等等，为后续安装『智能合约』提供准入条件。

启动智能合约

要启动智能合约，运行以下命令：

composer network start --networkName tutorial-network --networkVersion 0.0.1 --networkAdmin admin --networkAdminEnrollSecret adminpw --card PeerAdmin@hlfv1 --file networkadmin.card

输出结果如下：

Starting business network tutorial-network at version 0.0.1

Processing these Network Admins:
    userName: admin

✔ Starting business network definition. This may take a minute...
Successfully created business network card:
    Filename: networkadmin.card

Command succeeded

若有多个peer节点，需要等待一定时间才能启动完毕。该composer network start命令需要网络管理员卡，即，前面安装的PeerAdmin@hlfv1，以及智能合约名称和版本、要创建的业务网卡文件的名称『networkadmin.card』，以准备将其导入为业务网卡。

导入智能合约的业务网卡

在上面步骤中，已经通过命令生成了『networkadmin.card』-用于后续的网络测试的访问控制文件，通过将此文件导入到区块链网络中，即可进行该智能合约的相关逻辑代码的测试。导入命令如下：

composer card import --file networkadmin.card

输出结果如下：

Successfully imported business network card
    Card file: networkadmin.card
    Card name: admin@tutorial-network

Command succeeded

检测智能合约是否成功

导入了具体的业务网卡『networkadmin.card』，原则上通过composer network的ping命令可以查看到是否已经完成了发布。

composer network ping --card admin@tutorial-network

其中admin@tutorial-network为『networkAdmin.card』中的以管理员账号+@+智能合约名称为组合的合约代号，通过ping命令，可以查看该合约是否已经安装，具体输出如下：

The connection to the network was successfully tested: tutorial-network
    Business network version: 0.0.1
    Composer runtime version: 0.19.5
    participant: org.hyperledger.composer.system.NetworkAdmin#admin
    identity: org.hyperledger.composer.system.Identity#ffc4c2027f466a1c63c2912e5a724fa3d4d9f0d5ab4dcc02207a445ff80e2bd4

Command succeeded

至此，智能合约已经从开发并安装到节点中了，恭喜！！！

此时，docker的进程多了一个新的智能合约的容器，如下：

CONTAINER ID        NAME                                             CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             
1ed7283b08fa        peer0.org1.example.com                           1.28%               42.54MiB / 1.925GiB   2.16%               426kB / 650kB       
f6d811ad71f0        ca.org1.example.com                              0.00%               5.965MiB / 1.925GiB   0.30%               10.5kB / 2.88kB     
073d0d94c129        couchdb                                          0.19%               93.07MiB / 1.925GiB   4.72%               190kB / 2.6MB       
269b305cf916        orderer.example.com                              0.00%               5.715MiB / 1.925GiB   0.29%               86.6kB / 75.4kB     
2a43ed6aceec        dev-peer0.org1.example.com-bless-network-0.0.1   0.00%               66.18MiB / 1.925GiB   3.36%               102kB / 150kB

容器名dev-peer0.org1.example.com-bless-network-0.0.1，则是新开发并发布的智能合约，合约以容器的形式存在并运行在区块链网络节点中，后续可以通过composer playground等web操作页面、rest服务器进行测试智能合约的可用性。至此，我们的智能合约已经发布完毕，下面将来验证我们的部署的情况，见证奇迹的时刻到了。

Step 5-生成REST服务器

hyperledger composer的可以基于业务网络生成定制的REST API接口。为了开发web应用程序，REST API提供了了与开发语言无关的抽象层。

要创建RESP API，导航到tutorial-network目录并执行以下命令：

composer-rest-server

输入admin@tutorial-network作为智能合约的名称。
选择决不询问是否在生成的API中使用名称空间时使用名称空间。
选择没有当被问及是否保护生成的API。
选择是当被问及是否启用事件发布时。
选择没有当被问及是否启用TLS安全。

总体的输出结果如下：

? Enter the name of the business network card to use: admin@tutorial-network
? Specify if you want namespaces in the generated REST API: never use namespaces
? Specify if you want to use an API key to secure the REST API: No
? Specify if you want to enable authentication for the REST API using Passport: No
? Specify if you want to enable event publication over WebSockets: Yes
? Specify if you want to enable TLS security for the REST API: No

To restart the REST server using the same options, issue the following command:
   composer-rest-server -c admin@tutorial-network -n never -w true

Discovering types from business network definition ...
Discovered types from business network definition
Generating schemas for all types in business network definition ...
Generated schemas for all types in business network definition
Adding schemas for all types to Loopback ...
Added schemas for all types to Loopback
Web server listening at: http://localhost:3000
Browse your REST API at http://localhost:3000/explorer

生成的API连接到部署的区块链和业务网络，打开浏览器，输入Url：http://localhost:3000/explorer 进行访问REST API的web页面。RESP API封装了业务逻辑、数据模型、事务的GET和POST的方法。通过此页面可以进行报文请求及响应。请求的报文会直接调用智能合约上的代码，并执行。通过blockchain-explorer等工具可以看到具体的写入区块和交易。

Step 6-生成Angular客户端

Hyperledger Composer还可以生成针对REST API运行的Angular应用程序。同样，要创建您的Angular应用程序，请导航至tutorial-network根目录。

运行以下命令

yo hyperledger-composer:angular

选择是当被要求连接到运行业务网络时
输入标准package.json问题（项目名称，说明，作者姓名，作者电子邮件，许可证）
输入智能合约名称admin@tutorial-network
选择连接到现有的REST API
输入http://localhost为REST服务器地址
输入3000用于服务器端口
选择名称空间不被使用

最后执行完步骤8后，Angular generator将为该项目创建并安装所有依赖项。

最后通过npm start的命令启动该angular应用，访问地址为：http://localhost:4200

总结

通过以上步骤，完成了智能合约的生成–>代码开发–>安装发布–>REST API服务端创建–>客户端的创建整体流程。在新的智能合约的开发中可以参考此流程。
感谢开源组织为我们提供了整体的区块链解决方案，合约创建，部署也方便，接下来就是区块链节点的统一管理了，此时的hyperledger又提供了一个很强大的开源工程cello，下一步在进行研究。